From 50ab749f4bc6378767f2c252b30e128b577c66f8 Mon Sep 17 00:00:00 2001 From: Damon Chaplin Date: Tue, 1 Feb 2000 04:27:56 +0000 Subject: [PATCH] ran make templates. 2000-02-02 Damon Chaplin * gdk/tmpl/*.sgml: ran make templates. * gdk/gdk-docs.sgml: rearranged sections. * gdk/tmpl/events.sgml: documented. * gdk/tmpl/general.sgml: documented. * gdk/tmpl/rgb.sgml: fixed a few '@' -> '#'. * gdk/gdk-sections.txt: rearranged a few bits, including moving GdkWChar and related functions from the input method section to the font section, and GdkCapStyle etc. from Drawing Primitives to GCs. * gdk/tmpl/images.sgml: documented. * gdk/tmpl/drawing.sgml: updated. * gdk/tmpl/regions.sgml: updated. * gdk/tmpl/input_contexts.sgml: documented. * gdk/tmpl/input_methods.sgml: documented. * gdk/tmpl/selections.sgml: changed xref to a link since Jade says a xref to a RefEntry is not supported. --- docs/reference/ChangeLog | 29 ++ docs/reference/gdk/gdk-decl.txt | 38 +-- docs/reference/gdk/gdk-docs.sgml | 41 ++- docs/reference/gdk/gdk-sections.txt | 92 ++++-- docs/reference/gdk/tmpl/drawing.sgml | 187 ++++-------- docs/reference/gdk/tmpl/event_structs.sgml | 8 + docs/reference/gdk/tmpl/events.sgml | 258 ++++++++++++----- docs/reference/gdk/tmpl/fonts.sgml | 62 ++++ docs/reference/gdk/tmpl/gcs.sgml | 296 +++++++++---------- docs/reference/gdk/tmpl/general.sgml | 305 +++++++++++++------- docs/reference/gdk/tmpl/images.sgml | 159 ++++++---- docs/reference/gdk/tmpl/input_contexts.sgml | 261 +++++++++++------ docs/reference/gdk/tmpl/input_methods.sgml | 210 ++++++++++---- docs/reference/gdk/tmpl/properties.sgml | 7 + docs/reference/gdk/tmpl/regions.sgml | 164 ++++++----- docs/reference/gdk/tmpl/rgb.sgml | 258 +++++++++-------- docs/reference/gdk/tmpl/selections.sgml | 8 +- 17 files changed, 1461 insertions(+), 922 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 7c1f829d26..320c8cd2b2 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,32 @@ +2000-02-02 Damon Chaplin + + * gdk/tmpl/*.sgml: ran make templates. + + * gdk/gdk-docs.sgml: rearranged sections. + + * gdk/tmpl/events.sgml: documented. + + * gdk/tmpl/general.sgml: documented. + + * gdk/tmpl/rgb.sgml: fixed a few '@' -> '#'. + + * gdk/gdk-sections.txt: rearranged a few bits, including moving + GdkWChar and related functions from the input method section to the + font section, and GdkCapStyle etc. from Drawing Primitives to GCs. + + * gdk/tmpl/images.sgml: documented. + + * gdk/tmpl/drawing.sgml: updated. + + * gdk/tmpl/regions.sgml: updated. + + * gdk/tmpl/input_contexts.sgml: documented. + + * gdk/tmpl/input_methods.sgml: documented. + + * gdk/tmpl/selections.sgml: changed xref to a link since Jade says + a xref to a RefEntry is not supported. + 2000-01-19 Damon Chaplin * gtk/tmpl/gtkscrollbar.sgml: Started. diff --git a/docs/reference/gdk/gdk-decl.txt b/docs/reference/gdk/gdk-decl.txt index 9bfb10e8a8..cd75a1e2a3 100644 --- a/docs/reference/gdk/gdk-decl.txt +++ b/docs/reference/gdk/gdk-decl.txt @@ -870,17 +870,17 @@ GdkImage *image gdk_colormap_new GdkColormap * -GdkVisual *visual,gint allocate +GdkVisual *visual,gint allocate gdk_colormap_ref GdkColormap * -GdkColormap *cmap +GdkColormap *cmap gdk_colormap_unref void -GdkColormap *cmap +GdkColormap *cmap gdk_colormap_get_system @@ -895,42 +895,42 @@ void gdk_colormap_change void -GdkColormap *colormap,gint ncolors +GdkColormap *colormap,gint ncolors gdk_colormap_alloc_colors gint -GdkColormap *colormap,GdkColor *colors,gint ncolors,gboolean writeable,gboolean best_match,gboolean *success +GdkColormap *colormap,GdkColor *colors,gint ncolors,gboolean writeable,gboolean best_match,gboolean *success gdk_colormap_alloc_color gboolean -GdkColormap *colormap,GdkColor *color,gboolean writeable,gboolean best_match +GdkColormap *colormap,GdkColor *color,gboolean writeable,gboolean best_match gdk_colormap_free_colors void -GdkColormap *colormap,GdkColor *colors,gint ncolors +GdkColormap *colormap,GdkColor *colors,gint ncolors gdk_colormap_get_visual -GdkVisual * -GdkColormap *colormap +GdkVisual * +GdkColormap *colormap gdk_color_copy -GdkColor * -GdkColor *color +GdkColor * +GdkColor *color gdk_color_free void -GdkColor *color +GdkColor *color gdk_color_parse -gint -const gchar *spec,GdkColor *color +gboolean +const gchar *spec,GdkColor *color gdk_color_hash @@ -949,7 +949,7 @@ GdkColormap *colormap,GdkColor *colors,gint ncolors gdk_colors_alloc -gint +gboolean GdkColormap *colormap,gint contiguous,gulong *planes,gint nplanes,gulong *pixels,gint npixels @@ -959,22 +959,22 @@ GdkColormap *colormap,gulong *pixels,gint npixels,gulong planes gdk_color_white -gint +gboolean GdkColormap *colormap,GdkColor *color gdk_color_black -gint +gboolean GdkColormap *colormap,GdkColor *color gdk_color_alloc -gint +gboolean GdkColormap *colormap,GdkColor *color gdk_color_change -gint +gboolean GdkColormap *colormap,GdkColor *color diff --git a/docs/reference/gdk/gdk-docs.sgml b/docs/reference/gdk/gdk-docs.sgml index 022ded73b4..a656a33d8b 100644 --- a/docs/reference/gdk/gdk-docs.sgml +++ b/docs/reference/gdk/gdk-docs.sgml @@ -32,28 +32,41 @@ GDK &gdk-General; + + &gdk-Points-Rectangles-and-Regions; + &gdk-Graphics-Contexts; + &gdk-Drawing-Primitives; + &gdk-Bitmaps-and-Pixmaps; - &gdk-Images; &gdk-GdkRGB; + &gdk-Images; + &gdk-Colormaps-and-Colors; - &gdk-Fonts; - &gdk-Drawing-Primitives; - &gdk-Graphics-Contexts; + &gdk-Color-Contexts; &gdk-Visuals; + + &gdk-Fonts; + &gdk-Cursors; + &gdk-Windows; + + &gdk-Events; + &gdk-Event-Structures; + &gdk-Selections; + &gdk-Drag-and-Drop; + &gdk-Properties-and-Atoms; - &gdk-Input-Methods; - &gdk-Input-Contexts; - &gdk-Color-Contexts; - &gdk-Points-Rectangles-and-Regions; + &gdk-Threads; - &gdk-Key-Values; - &gdk-Input-Devices; - &gdk-Events; - &gdk-Event-Structures; - &gdk-Cursors; + &gdk-Input; - &gdk-Drag-and-Drop; + + &gdk-Input-Devices; + + &gdk-Key-Values; + + &gdk-Input-Methods; + &gdk-Input-Contexts; diff --git a/docs/reference/gdk/gdk-sections.txt b/docs/reference/gdk/gdk-sections.txt index 661ef50317..9f84c81067 100644 --- a/docs/reference/gdk/gdk-sections.txt +++ b/docs/reference/gdk/gdk-sections.txt @@ -7,35 +7,47 @@ gdk_init gdk_init_check gdk_exit -GdkStatus -GDK_NONE -GDK_CURRENT_TIME -GDK_PRIORITY_EVENTS gdk_set_locale -gdk_get_show_events -gdk_set_show_events -gdk_add_client_message_filter gdk_set_sm_client_id -gdk_get_use_xshm -gdk_set_use_xshm + + gdk_get_display + + +gdk_flush + + gdk_screen_width gdk_screen_height gdk_screen_width_mm gdk_screen_height_mm + + gdk_pointer_grab gdk_pointer_ungrab +gdk_pointer_is_grabbed + + gdk_keyboard_grab gdk_keyboard_ungrab -gdk_pointer_is_grabbed -gdk_flush -gdk_beep + + gdk_key_repeat_disable gdk_key_repeat_restore + + +gdk_beep + + +gdk_get_use_xshm +gdk_set_use_xshm + + gdk_error_trap_push gdk_error_trap_pop +GdkStatus gdk_time_get gdk_timer_get gdk_timer_set @@ -65,13 +77,14 @@ gdk_bitmap_unref Images images GdkImage +gdk_image_new GdkImageType gdk_image_new_bitmap -gdk_image_new gdk_image_get +gdk_image_destroy + gdk_image_put_pixel gdk_image_get_pixel -gdk_image_destroy
@@ -162,16 +175,16 @@ gdk_char_measure gdk_string_height gdk_text_height gdk_char_height + + +GdkWChar +gdk_wcstombs +gdk_mbstowcs
Drawing Primitives drawing -GdkFill -GdkLineStyle -GdkCapStyle -GdkJoinStyle - gdk_draw_point gdk_draw_points gdk_draw_line @@ -189,8 +202,10 @@ gdk_draw_text_wc gdk_draw_pixmap -gdk_draw_bitmap gdk_draw_image + + +gdk_draw_bitmap
@@ -213,6 +228,7 @@ gdk_gc_set_background gdk_gc_set_font gdk_gc_set_function gdk_gc_set_fill +GdkFill gdk_gc_set_tile gdk_gc_set_stipple gdk_gc_set_ts_origin @@ -224,6 +240,9 @@ gdk_gc_set_subwindow GdkSubwindowMode gdk_gc_set_exposures gdk_gc_set_line_attributes +GdkLineStyle +GdkCapStyle +GdkJoinStyle gdk_gc_set_dashes gdk_gc_copy
@@ -347,6 +366,7 @@ gdk_selection_send_notify Properties and Atoms properties GdkAtom +GDK_NONE gdk_text_property_to_text_list gdk_free_text_list gdk_string_to_compound_text @@ -363,29 +383,29 @@ gdk_property_delete Input Methods input_methods GdkIMStyle -GdkWChar gdk_im_ready -gdk_im_begin -gdk_im_end gdk_im_decide_style gdk_im_set_best_style -gdk_wcstombs -gdk_mbstowcs + +gdk_im_begin +gdk_im_end
Input Contexts input_contexts GdkIC -GdkICAttr -GdkICAttributesType gdk_ic_new gdk_ic_destroy +gdk_ic_get_events gdk_ic_get_style -gdk_ic_set_attr gdk_ic_get_attr -gdk_ic_get_events +gdk_ic_set_attr + + +GdkICAttr +GdkICAttributesType gdk_ic_attr_new gdk_ic_attr_destroy
@@ -502,7 +522,10 @@ gdk_input_exit events GdkEventType GdkEventMask +GDK_CURRENT_TIME +GDK_PRIORITY_EVENTS + gdk_events_pending gdk_event_peek gdk_event_get @@ -511,12 +534,19 @@ gdk_event_put gdk_event_copy gdk_event_free gdk_event_get_time -gdk_event_handler_set -gdk_event_send_client_message + +gdk_event_handler_set GdkEventFunc + +gdk_event_send_client_message gdk_event_send_clientmessage_toall +gdk_add_client_message_filter + + +gdk_get_show_events +gdk_set_show_events
diff --git a/docs/reference/gdk/tmpl/drawing.sgml b/docs/reference/gdk/tmpl/drawing.sgml index a29bf9aad5..f9589d8fdb 100644 --- a/docs/reference/gdk/tmpl/drawing.sgml +++ b/docs/reference/gdk/tmpl/drawing.sgml @@ -25,100 +25,80 @@ more information. - + -Used to specify the way in which drawing operations are performed. -See gdk_gc_set_fill(). +Draws a point, using the foreground color and other attributes of the #GdkGC. -@GDK_SOLID: graphics are drawn in a solid color, usually the foreground color -of the #GdkGC. -@GDK_TILED: graphics are drawn using a tile pixmap. See gdk_gc_set_tile(). -@GDK_STIPPLED: graphics are drawn with a stipple (a pixmap with a depth of 1). -Bits set in the stipple are drawn in the foreground color. Bits not set in the -stipple are left as they are. See gdk_gc_set_stipple(). -@GDK_OPAQUE_STIPPLED: graphics are drawn with a stipple, as in @GDK_STIPPLED, -except that the bits not set in the stipple are drawn in the background color -instead of being left as they are. See gdk_gc_set_stipple(). - - +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). +@gc: a #GdkGC. +@x: the x coordinate of the point. +@y: the y coordinate of the point. + + + -The method for determining which pixels are included in a region, when -creating a #GdkRegion from a polygon. -The fill rule is only relevant for polygons which overlap themselves. +Draws a number of points, using the foreground color and other attributes of +the #GdkGC. -@GDK_EVEN_ODD_RULE: areas which are overlapped an odd number of times are -included in the region, while areas overlapped an even number of times are not. -@GDK_WINDING_RULE: overlapping areas are always included. +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). +@gc: a #GdkGC. +@points: an array of #GdkPoint structures. +@npoints: the number of points to be drawn. - + -Used to specify how lines are drawn. See gdk_gc_set_line_attributes(). +Draws a line, using the foreground color and other attributes of the #GdkGC. -@GDK_LINE_SOLID: lines are drawn in a solid color, the foreground color. -@GDK_LINE_ON_OFF_DASH: dashed lines are drawn, with the pixels between the -dashes left as they are. The #GdkCapStyle is applied to each end of the dashes. -@GDK_LINE_DOUBLE_DASH: dashed lines are drawn, alternating between the -foreground and background colors. The %GDK_CAP_BUTT style is used where -dashes and gaps meet. +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). +@gc: a #GdkGC. +@x1: the x coordinate of the start point. +@y1: the y coordinate of the start point. +@x2: the x coordinate of the end point. +@y2: the y coordinate of the end point. - - -Used to specify how the ends of lines and dashes are drawn. -See gdk_gc_set_line_attributes(). - -@GDK_CAP_NOT_LAST: this is equivalent to %GDK_CAP_BUTT, except that for a line -width of 0 the final endpoint is not drawn. -@GDK_CAP_BUTT: the ends of the line are square with no projection beyond the -endpoint. -@GDK_CAP_ROUND: the ends of the line are rounded using a circular arc centered -on the endpoint. This is equivalent to %GDK_CAP_BUTT when the line width is 0. -@GDK_CAP_PROJECTING: the ends of the line are square, but project beyond the -endpoint to a distance of half the line width. -This is equivalent to %GDK_CAP_BUTT when the line width is 0. - - + -Used to specify how the the joins between lines are drawn. -See gdk_gc_set_line_attributes(). +Draws a series of lines connecting the given points. +The way in which joins between lines are draw is determined by the +#GdkCapStyle value in the #GdkGC. This can be set with +gdk_gc_set_line_attributes(). -@GDK_JOIN_MITER: the ends of the lines are extended to meet at a point. -If the angle between the lines is less than 11 degrees, %GDK_JOIN_BEVEL is -used instead. -@GDK_JOIN_ROUND: the ends of the lines are rounded with a circular arc -centered on the joinpoint, with a diameter equal to the line width. -@GDK_JOIN_BEVEL: the lines have %GDK_CAP_BUTT cap styles, with the triangular -notch filled. +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). +@gc: a #GdkGC. +@points: an array of #GdkPoint structures specifying the endpoints of the +lines. +@npoints: the size of the @points array. + - + -Draws a point, using the foreground color and other attributes of the #GdkGC. +Draws a number of unconnected lines. @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). @gc: a #GdkGC. -@x: the x coordinate of the point. -@y: the y coordinate of the point. +@segs: an array of #GdkSegment structures specifying the start and end points +of the lines to be drawn, +@nsegs: the number of line segments to draw, i.e. the size of the @segs array. - + -Draws a line, using the foreground color and other attributes of the #GdkGC. +Specifies the start and end point of a line for use by the gdk_draw_segments() +function. -@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). -@gc: a #GdkGC. @x1: the x coordinate of the start point. @y1: the y coordinate of the start point. @x2: the x coordinate of the end point. @y2: the y coordinate of the end point. - Draws a rectangular outline or filled rectangle, using the foreground color @@ -238,83 +218,22 @@ the right edge of the source pixmap. to the bottom edge of the source pixmap. - - - - - -@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). -@gc: -@src: -@xsrc: -@ysrc: -@xdest: -@ydest: -@width: -@height: - - - - - -@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). -@gc: -@image: -@xsrc: -@ysrc: -@xdest: -@ydest: -@width: -@height: - - - - -Draws a number of points, using the foreground color and other attributes of -the #GdkGC. - - -@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). -@gc: a #GdkGC. -@points: an array of #GdkPoint structures. -@npoints: the number of points to be drawn. - - - - - - - -@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). -@gc: -@segs: -@nsegs: - - - - - - - -@x1: -@y1: -@x2: -@y2: - - - -Draws a series of lines connecting the given points. -The way in which joins between lines are draw is determined by the -#GdkCapStyle value in the #GdkGC. This can be set with -gdk_gc_set_line_attributes(). +Draws a #GdkImage onto a drawable. +The depth of the #GdkImage must match the depth of the #GdkDrawable. @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). @gc: a #GdkGC. -@points: an array of #GdkPoint structures specifying the endpoints of the -lines. -@npoints: the number of endpoints. +@image: the #GdkImage to draw. +@xsrc: the left edge of the source rectangle within @image. +@ysrc: the top of the source rectangle within @image. +@xdest: the x coordinate of the destination within @drawable. +@ydest: the y coordinate of the destination within @drawable. +@width: the width of the area to be copied, or -1 to make the area extend to +the right edge of @image. +@height: the height of the area to be copied, or -1 to make the area extend +to the bottom edge of @image. diff --git a/docs/reference/gdk/tmpl/event_structs.sgml b/docs/reference/gdk/tmpl/event_structs.sgml index ce5ba37aab..75961e8b31 100644 --- a/docs/reference/gdk/tmpl/event_structs.sgml +++ b/docs/reference/gdk/tmpl/event_structs.sgml @@ -232,6 +232,14 @@ as graphics tablets. It defaults to 0.5. @time: @state: + + + + + +@GDK_PROPERTY_NEW_VALUE: +@GDK_PROPERTY_DELETE: + diff --git a/docs/reference/gdk/tmpl/events.sgml b/docs/reference/gdk/tmpl/events.sgml index 126950238a..9a4fe5e96e 100644 --- a/docs/reference/gdk/tmpl/events.sgml +++ b/docs/reference/gdk/tmpl/events.sgml @@ -2,59 +2,102 @@ Events - +functions for handling events from the window system. - +This section describes functions dealing with events from the window system. + + +In GTK+ applications the events are handled automatically in +gtk_main_do_event() and passed on to the appropriate widgets, so these +functions are rarely needed. Though some of the fields in the +Event Structures are useful. - + + +Event Structures + +The structs used for each type of event. + + + - +Specifies the type of the event. + + +Do not confuse these events with the signals that GTK+ widgets emit. +Although many of these events result in corresponding signals being emitted, +the events are often transformed or filtered along the way. -@GDK_NOTHING: -@GDK_DELETE: -@GDK_DESTROY: -@GDK_EXPOSE: -@GDK_MOTION_NOTIFY: -@GDK_BUTTON_PRESS: -@GDK_2BUTTON_PRESS: -@GDK_3BUTTON_PRESS: -@GDK_BUTTON_RELEASE: -@GDK_KEY_PRESS: -@GDK_KEY_RELEASE: -@GDK_ENTER_NOTIFY: -@GDK_LEAVE_NOTIFY: -@GDK_FOCUS_CHANGE: -@GDK_CONFIGURE: -@GDK_MAP: -@GDK_UNMAP: -@GDK_PROPERTY_NOTIFY: -@GDK_SELECTION_CLEAR: -@GDK_SELECTION_REQUEST: -@GDK_SELECTION_NOTIFY: -@GDK_PROXIMITY_IN: -@GDK_PROXIMITY_OUT: -@GDK_DRAG_ENTER: -@GDK_DRAG_LEAVE: -@GDK_DRAG_MOTION: -@GDK_DRAG_STATUS: -@GDK_DROP_START: -@GDK_DROP_FINISHED: -@GDK_CLIENT_EVENT: -@GDK_VISIBILITY_NOTIFY: -@GDK_NO_EXPOSE: +@GDK_NOTHING: a special code to indicate a null event. +@GDK_DELETE: the window manager has requested that the toplevel window be +hidden or destroyed, usually when the user clicks on a special icon in the +title bar. +@GDK_DESTROY: the window has been destroyed. +@GDK_EXPOSE: all or part of the window has become visible and needs to be +redrawn. +@GDK_MOTION_NOTIFY: the pointer (usually a mouse) has moved. +@GDK_BUTTON_PRESS: a mouse button has been pressed. +@GDK_2BUTTON_PRESS: a mouse button has been double-clicked (clicked twice +within a short period of time). Note that each click also generates a +%GDK_BUTTON_PRESS event. +@GDK_3BUTTON_PRESS: a mouse button has been clicked 3 times in a short period +of time. Note that each click also generates a %GDK_BUTTON_PRESS event. +@GDK_BUTTON_RELEASE: a mouse button has been released. +@GDK_KEY_PRESS: a key has been pressed. +@GDK_KEY_RELEASE: a key has been released. +@GDK_ENTER_NOTIFY: the pointer has entered the window. +@GDK_LEAVE_NOTIFY: the pointer has left the window. +@GDK_FOCUS_CHANGE: the keyboard focus has entered or left the window. Note that +in GTK+ keyboard focus is handled mostly within GTK+ itself, so it is usually +only toplevel windows which receive these events. +@GDK_CONFIGURE: the size, position or stacking order of the window has changed. +Note that GTK+ discards these events for %GDK_WINDOW_CHILD windows. +@GDK_MAP: the window has been mapped. +@GDK_UNMAP: the window has been unmapped. +@GDK_PROPERTY_NOTIFY: a property on the window has been changed or deleted. +@GDK_SELECTION_CLEAR: the application has lost ownership of a selection. +@GDK_SELECTION_REQUEST: another application has requested a selection. +@GDK_SELECTION_NOTIFY: a selection has been received. +@GDK_PROXIMITY_IN: an input device has moved into contact with a sensing +surface (e.g. a touchscreen or graphics tablet). +@GDK_PROXIMITY_OUT: an input device has moved out of contact with a sensing +surface. +@GDK_DRAG_ENTER: the mouse has entered the window while a drag is in progress. +@GDK_DRAG_LEAVE: the mouse has left the window while a drag is in progress. +@GDK_DRAG_MOTION: the mouse has moved in the window while a drag is in +progress. +@GDK_DRAG_STATUS: the status of the drag operation initiated by the window +has changed. +@GDK_DROP_START: a drop operation onto the window has started. +@GDK_DROP_FINISHED: the drop operation initiated by the window has completed. +@GDK_CLIENT_EVENT: a message has been received from another application. +@GDK_VISIBILITY_NOTIFY: the window visibility status has changed. +@GDK_NO_EXPOSE: indicates that the source region was completely available +when parts of a drawable were copied. This is not very useful. - +A set of bit-flags to indicate which events a window is to receive. +Most of these masks map onto one or more of the #GdkEventType event types +above. + + +%GDK_POINTER_MOTION_HINT_MASK is a special mask which is used to reduce the +number of %GDK_MOTION_NOTIFY events received. Normally a %GDK_MOTION_NOTIFY +event is received each time the mouse moves. However, if the application +spends a lot of time processing the event (updating the display, for example), +it can easily lag behind the position of the mouse. When using the +%GDK_POINTER_MOTION_HINT_MASK the server will only send %GDK_MOTION_NOTIFY +events when the application asks for them, by calling gdk_window_get_pointer(). @GDK_EXPOSURE_MASK: @@ -77,109 +120,186 @@ Events @GDK_PROXIMITY_IN_MASK: @GDK_PROXIMITY_OUT_MASK: @GDK_SUBSTRUCTURE_MASK: -@GDK_ALL_EVENTS_MASK: +@GDK_ALL_EVENTS_MASK: the combination of all the above event masks. - + + +Represents the current time, and can be used anywhere a time is expected. + + + + + +This is the priority that events from the X server are given in the +GLib Main Loop. + + + + + +Checks if any events are waiting to be processed. -@Returns: +@Returns: TRUE if any events are pending. - +Gets a copy of the first #GdkEvent in the event queue. +(Note that this function will not get more events from the X server. +It only checks the events that have already been moved to the GDK event queue.) -@Returns: +@Returns: a copy of the first #GdkEvent on the event queue, or NULL if no +events are in the queue. The returned #GdkEvent should be freed with +gdk_event_free(). - +Gets the next #GdkEvent to be processed, fetching events from the X server if +necessary. -@Returns: +@Returns: the next #GdkEvent to be processed, or NULL if no events are pending. +The returned #GdkEvent should be freed with gdk_event_free(). - +Waits for a GraphicsExpose or NoExpose event from the X server. +This is used in the #GtkText and #GtkCList widgets in GTK+ to make sure any +GraphicsExpose events are handled before the widget is scrolled. -@window: -@Returns: +@window: the #GdkWindow to wait for the events for. +@Returns: a #GdkEventExpose if a GraphicsExpose was received, or NULL if a +NoExpose event was received. - +Appends a copy of the given event onto the front of the event queue. -@event: +@event: a #GdkEvent. - +Copies a #GdkEvent, copying or incrementing the reference count of the +resources associated with it (e.g. #GdkWindow's and strings). -@event: -@Returns: +@event: a #GdkEvent. +@Returns: a copy of @event. The returned #GdkEvent should be freed with +gdk_event_free(). - +Frees a #GdkEvent, freeing or decrementing any resources associated with it. +Note that this function should only be called with events returned from +gdk_event_peek(), gdk_event_get(), gdk_event_get_graphics_expose() and +gdk_event_copy(). -@event: +@event: a #GdkEvent. - +Gets the timestamp from a #GdkEvent. -@event: -@Returns: +@event: a #GdkEvent. +@Returns: the timestamp from @event, or #GDK_CURRENT_TIME if the event has +no timestamp. +Sets the function to call to handle all events from GDK. + + +Note that GTK+ uses this to install its own event handler, so it is probably +not useful for GTK+ applications. + + +@func: the function to call to handle events from GDK. +@data: user data to pass to the function. +@notify: the function to call when the handler function is removed, i.e. when +gdk_event_handler_set() is called with another event handler. + + + +Specifies the type of function passed to gdk_event_handler_set() to handle +all GDK events. -@func: -@data: -@notify: +@event: the #GdkEvent to process. +@data: user data set when the event handler was installed with +gdk_event_handler_set(). - +Sends an X ClientMessage event to a given window. + + +This could be used for communicating between different applications, +though the amount of data is limited to 20 bytes. -@event: -@xid: -@Returns: +@event: the #GdkEvent to send, which should be a #GdkEventClient. +@xid: the window to send the X ClientMessage event to. +@Returns: non-zero on success. - + + +Sends an X ClientMessage event to all toplevel windows. + +Toplevel windows are determined by checking for the WM_STATE property, as +described in the Inter-Client Communication Conventions Manual (ICCCM). +If no windows are found with the WM_STATE property set, the message is sent +to all children of the root window. + + +@event: the #GdkEvent to send, which should be a #GdkEventClient. + + + +Adds a filter to be called when X ClientMessage events are received. -@event: -@data: +@message_type: the type of ClientMessage events to receive. This will be +checked against the message_type field of the +XClientMessage event struct. +@func: the function to call to process the event. +@data: user data to pass to @func. - + +Returns non-zero if event debugging output is enabled. + +@Returns: non-zero if event debugging output is enabled. + + + + +Sets whether event debugging information is output. +Note that GTK+ must be compiled with debugging enabled, i.e. using the +'--enable-debug' configure option. -@event: +@show_events: TRUE to output event debugging information. diff --git a/docs/reference/gdk/tmpl/fonts.sgml b/docs/reference/gdk/tmpl/fonts.sgml index 841b58208a..479b115846 100644 --- a/docs/reference/gdk/tmpl/fonts.sgml +++ b/docs/reference/gdk/tmpl/fonts.sgml @@ -579,3 +579,65 @@ relation to the baseline. See gdk_text_extents(). @Returns: the height of the character in pixels. + + +Specifies a wide character type, used to represent character codes. +This is needed since some native languages have character sets which have +more than 256 characters (Japanese and Chinese, for example). + + +Wide character values between 0 and 127 are always identical in meaning to +the ASCII character codes. The wide character value 0 is often used to +terminate strings of wide characters in a similar way to normal strings +using the char type. + + +An alternative to wide characters is multi-byte characters, which extend +normal char strings to cope with larger character sets. As the name suggests, +multi-byte characters use a different number of bytes to store different +character codes. For example codes 0-127 (i.e. the ASCII codes) often +use just one byte of memory, while other codes may use 2, 3 or even 4 bytes. +Multi-byte characters have the advantage that they can often be used in an +application with little change, since strings are still represented as arrays +of char values. However multi-byte strings are much easier to manipulate since +the character are all of the same size. + + +Applications typically use wide characters to represent character codes +internally, and multi-byte strings when saving the characters to a file. +The gdk_wcstombs() and gdk_mbstowcs() functions can be used to convert from +one representation to the other. + + +See the 'Extended Characters' section of the GNU C Library Reference Manual +for more detailed information on wide and multi-byte characters. + + + + + +Converts a wide character string to a multi-byte string. +(The function name comes from an acronym of 'Wide Character String TO +Multi-Byte String'). + + +@src: a wide character string. +@Returns: the multi-byte string corresponding to @src, or NULL if the +conversion failed. The returned string should be freed with g_free() when no +longer needed. + + + + +Converts a multi-byte string to a wide character string. +(The function name comes from an acronym of 'Multi-Byte String TO Wide +Character String'). + + +@dest: the space to place the converted wide character string into. +@src: the multi-byte string to convert, which must be null-terminated. +@dest_max: the maximum number of wide characters to place in @dest. +@Returns: the number of wide characters written into @dest, or -1 if the +conversion failed. + + diff --git a/docs/reference/gdk/tmpl/gcs.sgml b/docs/reference/gdk/tmpl/gcs.sgml index e8da61fbc0..4ec3f32425 100644 --- a/docs/reference/gdk/tmpl/gcs.sgml +++ b/docs/reference/gdk/tmpl/gcs.sgml @@ -185,48 +185,6 @@ A set of bit flags used to indicate which fields @GDK_GC_CAP_STYLE: @GDK_GC_JOIN_STYLE: - - -Determines how primitives are drawn. - - - - - - -GDK_SOLID -draw with the foreground color. - - - -GDK_TILED -draw with a tiled pixmap. - - - -GDK_STIPPLED -draw using the stipple bitmap. Pixels corresponding -to bits in the stipple bitmap that are set will be drawn in the -foreground color; pixels corresponding to bits that are -not set will be left untouched. - - - -GDK_OPAQUE_STIPPLED -draw using the stipple bitmap. Pixels corresponding -to bits in the stipple bitmap that are set will be drawn in the -foreground color; pixels corresponding to bits that are -not set will be drawn with the background color. - - - - - -@GDK_SOLID: -@GDK_TILED: -@GDK_STIPPLED: -@GDK_OPAQUE_STIPPLED: - Determines how the bit values for the source pixels are combined with @@ -253,111 +211,6 @@ useful. For bitmaps, %GDK_AND and %GDK_OR are also useful. @GDK_NAND: @GDK_SET: - - -Determines how lines are drawn. - - - - - - -GDK_LINE_SOLID -lines are drawn solid. - - - -GDK_LINE_ON_OFF_DASH -even segments are drawn; odd segments are not drawn. - - - -GDK_LINE_DOUBLE_DASH -even segments are normally. Odd segments are drawn -in the background color if the fill style is %GDK_SOLID, -or in the background color masked by the stipple if the -fill style is %GDK_STIPPLED. - - - - - -@GDK_LINE_SOLID: -@GDK_LINE_ON_OFF_DASH: -@GDK_LINE_DOUBLE_DASH: - - - -Determines how the end of lines are drawn. - - - - - - -GDK_CAP_NOT_LAST -the same as %GDK_CAP_BUTT for lines of non-zero width. - for zero width lines, the final point on the line - will not be drawn. - - - -GDK_CAP_BUTT -the ends of the lines are drawn squared off and extending - to the coordinates of the end point. - - - -GDK_CAP_ROUND -the ends of the lines are drawn as semicircles with the - diameter equal to the line width and centered at the - end point. - - - -GDK_CAP_PROJECTING -the ends of the lines are drawn squared off and extending - half the width of the line beyond the end point. - - - - -@GDK_CAP_NOT_LAST: -@GDK_CAP_BUTT: -@GDK_CAP_ROUND: -@GDK_CAP_PROJECTING: - - - -Determines how the joins between segments of a polygon are drawn. - - - - - - -GDK_JOIN_MITER -the sides of each line are extended to meet at an angle. - - - -GDK_JOIN_ROUND -the sides of the two lines are joined by a circular arc. - - - -GDK_JOIN_BEVEL -the sides of the two lines are joined by a straight line which - makes an equal angle with each line. - - - - - -@GDK_JOIN_MITER: -@GDK_JOIN_ROUND: -@GDK_JOIN_BEVEL: - Create a new graphics context with default values. @@ -468,6 +321,48 @@ Set the fill mode for a graphics context. @fill: the new fill mode. + + +Determines how primitives are drawn. + + + + + + +GDK_SOLID +draw with the foreground color. + + + +GDK_TILED +draw with a tiled pixmap. + + + +GDK_STIPPLED +draw using the stipple bitmap. Pixels corresponding +to bits in the stipple bitmap that are set will be drawn in the +foreground color; pixels corresponding to bits that are +not set will be left untouched. + + + +GDK_OPAQUE_STIPPLED +draw using the stipple bitmap. Pixels corresponding +to bits in the stipple bitmap that are set will be drawn in the +foreground color; pixels corresponding to bits that are +not set will be drawn with the background color. + + + + + +@GDK_SOLID: +@GDK_TILED: +@GDK_STIPPLED: +@GDK_OPAQUE_STIPPLED: + Set a tile pixmap for a graphics context. @@ -611,6 +506,111 @@ explanations of the arguments. @join_style: the in which lines are joined together. + + +Determines how lines are drawn. + + + + + + +GDK_LINE_SOLID +lines are drawn solid. + + + +GDK_LINE_ON_OFF_DASH +even segments are drawn; odd segments are not drawn. + + + +GDK_LINE_DOUBLE_DASH +even segments are normally. Odd segments are drawn +in the background color if the fill style is %GDK_SOLID, +or in the background color masked by the stipple if the +fill style is %GDK_STIPPLED. + + + + + +@GDK_LINE_SOLID: +@GDK_LINE_ON_OFF_DASH: +@GDK_LINE_DOUBLE_DASH: + + + +Determines how the end of lines are drawn. + + + + + + +GDK_CAP_NOT_LAST +the same as %GDK_CAP_BUTT for lines of non-zero width. + for zero width lines, the final point on the line + will not be drawn. + + + +GDK_CAP_BUTT +the ends of the lines are drawn squared off and extending + to the coordinates of the end point. + + + +GDK_CAP_ROUND +the ends of the lines are drawn as semicircles with the + diameter equal to the line width and centered at the + end point. + + + +GDK_CAP_PROJECTING +the ends of the lines are drawn squared off and extending + half the width of the line beyond the end point. + + + + +@GDK_CAP_NOT_LAST: +@GDK_CAP_BUTT: +@GDK_CAP_ROUND: +@GDK_CAP_PROJECTING: + + + +Determines how the joins between segments of a polygon are drawn. + + + + + + +GDK_JOIN_MITER +the sides of each line are extended to meet at an angle. + + + +GDK_JOIN_ROUND +the sides of the two lines are joined by a circular arc. + + + +GDK_JOIN_BEVEL +the sides of the two lines are joined by a straight line which + makes an equal angle with each line. + + + + + +@GDK_JOIN_MITER: +@GDK_JOIN_ROUND: +@GDK_JOIN_BEVEL: + Sets the way dashed-lines are drawn. Lines will be @@ -635,3 +635,5 @@ onto another graphics context. @dst_gc: the destination graphics context. @src_gc: the source graphics context. + + diff --git a/docs/reference/gdk/tmpl/general.sgml b/docs/reference/gdk/tmpl/general.sgml index a2fe3a5b29..87a746db38 100644 --- a/docs/reference/gdk/tmpl/general.sgml +++ b/docs/reference/gdk/tmpl/general.sgml @@ -2,11 +2,12 @@ General - +library initialization and miscellaneous functions. - +This section describes the GDK initialization functions and miscellaneous +utility functions. @@ -16,250 +17,330 @@ General - +Initializes the GDK library and connects to the X server. +If initialization fails, a warning message is output and the application +terminates with a call to exit(1). - -@argc: -@argv: - - - - +Any arguments used by GDK are removed from the array and @argc and @argv are +updated accordingly. - -@argc: -@argv: -@Returns: - - - - +GTK+ initializes GDK in gtk_init() and so this function is not usually needed +by GTK+ applications. -@error_code: +@argc: the number of command line arguments. +@argv: the array of command line arguments. - + - +Initializes the GDK library and connects to the X server, returning TRUE on +success. - -@GDK_OK: -@GDK_ERROR: -@GDK_ERROR_PARAM: -@GDK_ERROR_FILE: -@GDK_ERROR_MEM: - - - +Any arguments used by GDK are removed from the array and @argc and @argv are +updated accordingly. - - - - - +GTK+ initializes GDK in gtk_init() and so this function is not usually needed +by GTK+ applications. +@argc: the number of command line arguments. +@argv: the array of command line arguments. +@Returns: TRUE if initialization succeeded. - + - +Exits the application using the exit() system call. - - - - - +This routine is provided mainly for backwards compatability, since it used to +perform tasks necessary to exit the application cleanly. Those tasks are now +performed in a function which is automatically called on exit (via the use +of g_atexit()). -@Returns: +@error_code: the error code to pass to the exit() call. - + - +Initializes the support for internationalization by calling the setlocale() +system call. This function is called by gtk_set_locale() and so GTK+ +applications should use that instead. - -@Returns: - - - - +The locale to use is determined by the LANG environment variable, +so to run an application in a certain locale you can do something like this: + + + export LANG="fr" + ... run application ... + + - -@show_events: - - - - +If the locale is not supported by X then it is reset to the standard "C" +locale. -@message_type: -@func: -@data: +@Returns: the resulting locale. - +Sets the SM_CLIENT_ID property on the application's leader window so that +the window manager can save the application's state using the X11R6 ICCCM +session management protocol. - -@sm_client_id: - - - - +The leader window is automatically created by GDK and never shown. It's only +use is for session management. The WM_CLIENT_LEADER property is automatically +set on all X windows created by the application to point to the leader window. + + +See the X Session Management Library documentation for more information on +session management and the Inter-Client Communication Conventions Manual +(ICCCM) for information on the WM_CLIENT_LEADER property. (Both documents are +part of the X Windows distribution.) -@Returns: +@sm_client_id: the client id assigned by the session manager when the +connection was opened, or NULL to remove the property. - + - +Gets the name of the display, which usually comes from the DISPLAY +environment variable or the --display command line option. -@use_xshm: +@Returns: the name of the display. - + - +Flushes the X output buffer and waits until all requests have been processed +by the server. This is rarely needed by applications. It's main use is for +trapping X errors with gdk_error_trap_push() and gdk_error_trap_pop(). -@Returns: - +Returns the width of the screen in pixels. -@Returns: +@Returns: the width of the screen in pixels. - +Returns the height of the screen in pixels. -@Returns: +@Returns: the height of the screen in pixels. - +Returns the width of the screen in millimeters. +Note that on many X servers this value will not be correct. -@Returns: +@Returns: the width of the screen in millimeters, though it is not always +correct. - +Returns the height of the screen in millimeters. +Note that on many X servers this value will not be correct. -@Returns: +@Returns: the height of the screen in millimeters, though it is not always +correct. +Grabs the pointer (usually a mouse) so that all events are passed to this +application until the pointer is ungrabbed with gdk_pointer_ungrab(), or +the grab window becomes unviewable. +This overrides any previous pointer grab by this client. + + +Pointer grabs are used for operations which need complete control over mouse +events, even if the mouse leaves the application. +For example in GTK+ it is used for Drag and Drop, for dragging the handle in +the #GtkHPaned and #GtkVPaned widgets, and for resizing columns in #GtkCList +widgets. + + +Note that if the event mask of an X window has selected both button press and +button release events, then a button press event will cause an automatic +pointer grab until the button is released. +X does this automatically since most applications expect to receive button +press and release events in pairs. +It is equivalent to a pointer grab on the window with @owner_events set to +TRUE. + + +@window: the #GdkWindow which will own the grab (the grab window). +@owner_events: if FALSE then all pointer events are reported with respect to +@window and are only reported if selected by @event_mask. If TRUE then pointer +events for this application are reported as normal, but pointer events outside +this application are reported with respect to @window and only if selected by +@event_mask. In either mode, unreported events are discarded. +@event_mask: specifies the event mask, which is used in accordance with +@owner_events. +@confine_to: TRUE to confine the pointer to @window. If the pointer is outside +@window, it will automatically be moved to the closest edge of @window and +enter and leave events will be generated as necessary. +@cursor: the cursor to display while the grab is active. If this is NULL then +the normal cursors are used for @window and its descendants, and the cursor +for @window is used for all other windows. +@time: the timestamp of the event which led to this pointer grab. This usually +comes from a #GdkEventButton struct, though #GDK_CURRENT_TIME can be used if +the time isn't known. +@Returns: 0 if the grab was successful. + + + +Ungrabs the pointer, if it is grabbed by this application. -@window: -@owner_events: -@event_mask: -@confine_to: -@cursor: -@time: -@Returns: +@time: a timestamp from a #GdkEvent, or #GDK_CURRENT_TIME if no timestamp is +available. - + - +Returns TRUE if the pointer is currently grabbed by this application. + + +Note that the return value is not completely reliable since the X server may +automatically ungrab the pointer, without informing the application, if the +grab window becomes unviewable. It also does not take passive pointer grabs +into account. -@time: +@Returns: TRUE if the pointer is currently grabbed by this application. +Though this value is not always correct. - +Grabs the keyboard so that all events are passed to this +application until the keyboard is ungrabbed with gdk_keyboard_ungrab(). +This overrides any previous keyboard grab by this client. -@window: -@owner_events: -@time: -@Returns: +@window: the #GdkWindow which will own the grab (the grab window). +@owner_events: if FALSE then all keyboard events are reported with respect to +@window. If TRUE then keyboard events for this application are reported as +normal, but keyboard events outside this application are reported with respect +to @window. Both key press and key release events are alwasy reported, +independant of the event mask set by the application. +@time: a timestamp from a #GdkEvent, or #GDK_CURRENT_TIME if no timestamp is +available. +@Returns: 0 if the grab was successful. - +Ungrabs the keyboard, if it is grabbed by this application. -@time: +@time: a timestamp from a #GdkEvent, or #GDK_CURRENT_TIME if no timestamp is +available. - + - +Disables the keyboard auto-repeat mode. +This should be used with care as it may affect other applications. -@Returns: - + - +Restores the keyboard auto-repeat mode to its state when the application was +started. - +Emits a short beep. - + - +Returns TRUE if GDK will attempt to use the MIT-SHM shared memory extension. + + +The shared memory extension is used for #GdkImage, and consequently for +GdkRGB. +It enables much faster drawing by communicating with the X server through +SYSV shared memory calls. However, it can only be used if the X client and +server are on the same machine and the server supports it. +@Returns: TRUE if use of the MIT shared memory extension will be attempted. - + - +Sets whether the use of the MIT shared memory extension should be attempted. +This function is mainly for internal use. It is only safe for an application +to set this to FALSE, since if it is set to TRUE and the server does not +support the extension it may cause warning messages to be output. +@use_xshm: TRUE if use of the MIT shared memory extension should be attempted. - +This function allows X errors to be trapped instead of the normal behavior +of exiting the application. It should only be used if it is not possible to +avoid the X error in any other way. + +Trapping an X error. + + gdk_error_trap_push (); + + /* ... Call the X function which may cause an error here ... */ + + /* Flush the X queue to catch errors now. */ + gdk_flush (); + + if (gdk_error_trap_pop ()) + { + /* ... Handle the error here ... */ + } + + - +Removes the X error trap installed with gdk_error_trap_push(). -@Returns: +@Returns: the X error code, or 0 if no error occurred. diff --git a/docs/reference/gdk/tmpl/images.sgml b/docs/reference/gdk/tmpl/images.sgml index cb77444117..683d817f07 100644 --- a/docs/reference/gdk/tmpl/images.sgml +++ b/docs/reference/gdk/tmpl/images.sgml @@ -2,106 +2,155 @@ Images - +an area for bit-mapped graphics stored on the X Windows client. - +The #GdkImage type represents an area for drawing graphics. +It has now been superceded to a large extent by the much more flexible +GdkRGB functions. + + +To create an empty #GdkImage use gdk_image_new(). +To create a #GdkImage from bitmap data use gdk_image_new_bitmap(). +To create an image from part of a #GdkWindow use gdk_image_get(). + + +The image can be manipulated with gdk_image_get_pixel() and +gdk_image_put_pixel(), or alternatively by changing the actual pixel data. +Though manipulating the pixel data requires complicated code to cope with +the different formats that may be used. + + +To draw a #GdkImage in a #GdkWindow or #GdkPixmap use gdk_draw_image(). + + +To destroy a #GdkImage use gdk_image_destroy(). - + + + +Bitmaps and Pixmaps + +Graphics which are stored on the X Windows server. +Since these are stored on the server they can be drawn very quickly, and all +of the Drawing Primitives can be +used to draw on them. Their main disadvantage is that manipulating individual +pixels can be very slow. + + + + +GdkRGB + +Built on top of #GdkImage, this provides much more functionality, +including the dithering of colors to produce better output on low-color +displays. + + + + - +The #GdkImage struct contains information on the image and the pixel data. -@type: -@visual: -@byte_order: -@width: -@height: -@depth: -@bpp: -@bpl: -@mem: +@type: the type of the image. +@visual: the visual. +@byte_order: the byte order. +@width: the width of the image in pixels. +@height: the height of the image in pixels. +@depth: the depth of the image, i.e. the number of bits per pixel. +@bpp: the number of bytes per pixel. +@bpl: the number of bytes per line of the image. +@mem: the pixel data. - + - +Creates a new #GdkImage. -@GDK_IMAGE_NORMAL: -@GDK_IMAGE_SHARED: -@GDK_IMAGE_FASTEST: +@type: the type of the #GdkImage, one of %GDK_IMAGE_NORMAL, %GDK_IMAGE_SHARED +and %GDK_IMAGE_FASTEST. %GDK_IMAGE_FASTEST is probably the best choice, since +it will try creating a %GDK_IMAGE_SHARED image first and if that fails it will +then use %GDK_IMAGE_NORMAL. +@visual: the #GdkVisual to use for the image. +@width: the width of the image in pixels. +@height: the height of the image in pixels. +@Returns: a new #GdkImage, or NULL if the image could not be created. - - + + +Specifies the type of a #GdkImage. -@visual: -@data: -@width: -@height: -@Returns: +@GDK_IMAGE_NORMAL: The original X image type, which is quite slow since the +image has to be transferred from the client to the server to display it. +@GDK_IMAGE_SHARED: A faster image type, which uses shared memory to transfer +the image data between client and server. However this will only be available +if client and server are on the same machine and the shared memory extension +is supported by the server. +@GDK_IMAGE_FASTEST: Specifies that %GDK_IMAGE_SHARED should be tried first, +and if that fails then %GDK_IMAGE_NORMAL will be used. - - + - +Creates a new #GdkImage with a depth of 1 from the given data. -@type: -@visual: -@width: -@height: -@Returns: +@visual: the #GdkVisual to use for the image. +@data: the pixel data. +@width: the width of the image in pixels. +@height: the height of the image in pixels. +@Returns: a new #GdkImage. - +Gets part of a #GdkWindow and stores it in a new #GdkImage. -@window: -@x: -@y: -@width: -@height: -@Returns: +@window: the #GdkWindow to copy from. +@x: the left edge of the rectangle to copy from @window. +@y: the top edge of the rectangle to copy from @window. +@width: the width of the area to copy, in pixels. +@height: the height of the area to copy, in pixels. +@Returns: a new #GdkImage with a copy of the given area of @window. - + - +Destroys a #GdkImage, freeing any resources allocated for it. -@image: -@x: -@y: -@pixel: +@image: a #GdkImage. - + - +Sets a pixel in a #GdkImage to a given pixel value. -@image: -@x: -@y: -@Returns: +@image: a #GdkImage. +@x: the x coordinate of the pixel to set. +@y: the y coordinate of the pixel to set. +@pixel: the pixel value to set. - + - +Gets a pixel value at a specified position in a #GdkImage. -@image: +@image: a #GdkImage. +@x: the x coordinate of the pixel to get. +@y: the y coordinate of the pixel to get. +@Returns: the pixel value at the given position. diff --git a/docs/reference/gdk/tmpl/input_contexts.sgml b/docs/reference/gdk/tmpl/input_contexts.sgml index ce23f99e66..b655f10bb4 100644 --- a/docs/reference/gdk/tmpl/input_contexts.sgml +++ b/docs/reference/gdk/tmpl/input_contexts.sgml @@ -2,11 +2,14 @@ Input Contexts - +internationalized text input properties. - +A #GdkIC input context is used for each user interface element which supports +internationalized text input. See the +Input Methods section for an overview +of how internationalized text input works in GTK+. @@ -16,139 +19,225 @@ Input Contexts - +The #GdkIC struct is an opaque structure representing an input context +for use with the global Input Method. - + - +Creates a new #GdkIC using the given attributes. -@style: -@client_window: -@focus_window: -@filter_events: -@spot_location: -@line_spacing: -@cursor: -@preedit_fontset: -@preedit_area: -@preedit_area_needed: -@preedit_foreground: -@preedit_background: -@preedit_pixmap: -@preedit_colormap: -@status_fontset: -@status_area: -@status_area_needed: -@status_foreground: -@status_background: -@status_pixmap: -@status_colormap: +@attr: a #GdkICAttr struct containing attributes to use for the input context. +@mask: a #GdkICAttributesType mask specifying which of the attributes in @attr +are set. +@Returns: a new #GdkIC. - - + + +Destroys the input context. -@GDK_IC_STYLE: -@GDK_IC_CLIENT_WINDOW: -@GDK_IC_FOCUS_WINDOW: -@GDK_IC_FILTER_EVENTS: -@GDK_IC_SPOT_LOCATION: -@GDK_IC_LINE_SPACING: -@GDK_IC_CURSOR: -@GDK_IC_PREEDIT_FONTSET: -@GDK_IC_PREEDIT_AREA: -@GDK_IC_PREEDIT_AREA_NEEDED: -@GDK_IC_PREEDIT_FOREGROUND: -@GDK_IC_PREEDIT_BACKGROUND: -@GDK_IC_PREEDIT_PIXMAP: -@GDK_IC_PREEDIT_COLORMAP: -@GDK_IC_STATUS_FONTSET: -@GDK_IC_STATUS_AREA: -@GDK_IC_STATUS_AREA_NEEDED: -@GDK_IC_STATUS_FOREGROUND: -@GDK_IC_STATUS_BACKGROUND: -@GDK_IC_STATUS_PIXMAP: -@GDK_IC_STATUS_COLORMAP: -@GDK_IC_ALL_REQ: -@GDK_IC_PREEDIT_AREA_REQ: -@GDK_IC_PREEDIT_POSITION_REQ: -@GDK_IC_STATUS_AREA_REQ: +@ic: a #GdkIC. - - + + +Returns the mask of events that the input method needs to function properly. +This is typically called in a widget's realize method after creating the +#GdkIC. The returned event mask is then combined with the widget's +own event mask and applied using gdk_window_set_events(). -@attr: -@mask: -@Returns: +@ic: a #GdkIC. +@Returns: the mask of events that the input method needs to function +properly. - + - +Returns the pre-edit and status style of the #GdkIC. -@ic: +@ic: a #GdkIC. +@Returns: the pre-edit and status style of the #GdkIC. - + - +Gets attributes of a #GdkIC. -@ic: -@Returns: +@ic: a #GdkIC. +@attr: a #GdkICAttr struct to contain the returned attributes. +@mask: a #GdkICAttributesType mask specifying which attributes to get. +@Returns: a #GdkICAttributesType mask specifying which of the attributes +were not retrieved succesfully. - +Sets attributes of the #GdkIC. + + +Note that the GDK_IC_STYLE and GDK_IC_CLIENT_WINDOW attributes can only be set +when creating the #GdkIC, and the GDK_IC_FILTER_EVENTS attribute is read-only. -@ic: -@attr: -@mask: -@Returns: +@ic: a #GdkIC. +@attr: a #GdkICAttr struct containing attributes to use for the input context. +@mask: a #GdkICAttributesType mask specifying which of the attributes in @attr +are set. +@Returns: a #GdkICAttributesType mask indicating which of the attributes +were not set successfully. - + - +The #GdkICAttr struct is used when getting and setting attributes of the +input context. It is used together with a #GdkICAttributesType mask which +specifies which of the fields are being set or returned. -@ic: -@attr: -@mask: -@Returns: - +@style: the pre-edit and status style. This attribute is required when +creating the #GdkIC, and cannot be changed. +@client_window: the #GdkWindow in which the input method will display its +pre-edit and status areas or create subwindows. +The preedit_area and status_area attributes are specified relative to this +window. This attribute is required when creating the #GdkIC, and cannot be +changed. +@focus_window: the #GdkWindow which is to be used when editing text. +gdk_im_begin() sets this attribute before starting the text input process, +so it is normally not necessary to set it elsewhere. +@filter_events: the mask of events that the input method requires. +See the gdk_ic_get_events() function. This attribute is read-only and is +never changed. +@spot_location: the position of the insertion cursor, for use with the +%GDK_IM_PREEDIT_POSITION style. The y coordinate specifies the baseline of +the text. +@line_spacing: the line spacing to be used in the pre-edit and status areas +when displaying multi-line text. +@cursor: the cursor to use in the input method's windows. +If this attribute isn't set it is determined by the input method. +@preedit_fontset: the font to use for the pre-edit area. +If this attribute isn't set it is determined by the input method. +@preedit_area: the area in which the input method will display pre-editing +data, used for the %GDK_IM_PREEDIT_POSITION and %GDK_IM_PREEDIT_AREA styles. +@preedit_area_needed: the area that the input method requests for displaying +pre-editing data, used for the %GDK_IM_PREEDIT_POSITION and +%GDK_IM_PREEDIT_AREA styles. +@preedit_foreground: the foreground color to use for the pre-edit area. +This color must already be allocated in the preedit_colormap. +If this attribute isn't set it is determined by the input method. +@preedit_background: the background color to use for the pre-edit area. +This color must already be allocated in the preedit_colormap. +If this attribute isn't set it is determined by the input method. +@preedit_pixmap: the background pixmap to use for the pre-edit area. +If this attribute isn't set it is determined by the input method. +@preedit_colormap: the colormap the input method should use to allocate colors. +The default value is the colormap of client_window. +@status_fontset: the font to use for the status area. +If this attribute isn't set it is determined by the input method. +@status_area: the are that the input method will display status information in. +This is used for the %GDK_IM_STATUS_AREA style. +@status_area_needed: the size that the input method requests for displaying +status information, for the %GDK_IM_STATUS_AREA style. +@status_foreground: the foreground color to use for the status area. +This color must already be allocated in the status_colormap. +If this attribute isn't set it is determined by the input method. +@status_background: the background color to use for the status area. +This color must already be allocated in the status_colormap. +If this attribute isn't set it is determined by the input method. +@status_pixmap: the background pixmap to use for the status area. +If this attribute isn't set it is determined by the input method. +@status_colormap: the colormap the input method should use to allocate colors. +The default value is the colormap of client_window. - + - +The #GdkICAttributesType contains a set of bit-flags which are used to +specify which of the attributes in a #GdkICAttr are being set or returned. + + +It also contains several combinations of the flags which specify required +attributes for the various styles: + + +%GDK_IC_ALL_REQ: + +the set of attributes required for all styles. + + + + +%GDK_IC_PREEDIT_AREA_REQ: + +the set of additional attributes required for the +%GDK_IM_PREEDIT_AREA pre-edit style. + + + + +%GDK_IC_PREEDIT_POSITION_REQ: + +the set of additional attributes required for the +%GDK_IM_PREEDIT_POSITION pre-edit style. + + + + +%GDK_IC_STATUS_AREA_REQ: + +the set of additional attributes required for the +%GDK_IM_STATUS_AREA status style. + + + -@ic: -@Returns: - +@GDK_IC_STYLE: +@GDK_IC_CLIENT_WINDOW: +@GDK_IC_FOCUS_WINDOW: +@GDK_IC_FILTER_EVENTS: +@GDK_IC_SPOT_LOCATION: +@GDK_IC_LINE_SPACING: +@GDK_IC_CURSOR: +@GDK_IC_PREEDIT_FONTSET: +@GDK_IC_PREEDIT_AREA: +@GDK_IC_PREEDIT_AREA_NEEDED: +@GDK_IC_PREEDIT_FOREGROUND: +@GDK_IC_PREEDIT_BACKGROUND: +@GDK_IC_PREEDIT_PIXMAP: +@GDK_IC_PREEDIT_COLORMAP: +@GDK_IC_STATUS_FONTSET: +@GDK_IC_STATUS_AREA: +@GDK_IC_STATUS_AREA_NEEDED: +@GDK_IC_STATUS_FOREGROUND: +@GDK_IC_STATUS_BACKGROUND: +@GDK_IC_STATUS_PIXMAP: +@GDK_IC_STATUS_COLORMAP: +@GDK_IC_ALL_REQ: +@GDK_IC_PREEDIT_AREA_REQ: +@GDK_IC_PREEDIT_POSITION_REQ: +@GDK_IC_STATUS_AREA_REQ: - +Creates a new #GdkICAttr struct, with all fields set to 0. +The #GdkICAttr struct should be freed with gdk_ic_attr_destroy() when no +longer needed. -@Returns: +@Returns: a new #GdkICAttr struct. - +Destroys the given #GdkICAttr struct, freeing the allocated memory. -@attr: +@attr: a #GdkICAttr struct. diff --git a/docs/reference/gdk/tmpl/input_methods.sgml b/docs/reference/gdk/tmpl/input_methods.sgml index 0f86c13137..fe528dee3a 100644 --- a/docs/reference/gdk/tmpl/input_methods.sgml +++ b/docs/reference/gdk/tmpl/input_methods.sgml @@ -2,100 +2,212 @@ Input Methods - +support for internationalized text input. +Input Methods provide a way for complex character sets to be used in GTK+. +Languages such as Chinese, Japanese, and Korean (often abbreviated to CJK) +use a large number of ideographs, making it impossible to support all +characters with a simple keyboard. Instead, text is usually +pre-edited using a phonetic alphabet and then +composed to form the ideographs. + + +GTK+ makes use of the input method mechanism provided by the X Windows +platform. When a GTK+ application is started, it opens a connection to the +input method appropriate for the current locale (if any). + + +Widgets which handle textual input, such as #GtkEntry, need to do a number of +things to support internationalized text input: + + +When the widget is realized: +Check if an input method is being used with gdk_im_ready(). +If it is, create a new Input Context +using gdk_ic_new(). Find out which events the +Input Context needs to receive +with gdk_ic_get_events(), and make sure that the widget's window receives +these events using gdk_window_set_events(). + + + + +When the widget's size, state or cursor position changes: + +Update the appropriate +Input Context attributes +using gdk_ic_set_attr(). + + + + +When the keyboard focus enters or leaves the widget: + +Call gdk_im_begin() or gdk_im_end() to start or finish editing the text. + + + + +When the widget receives a key_press event: + +The string and length +fields of the #GdkEventKey struct should be used to insert the composed text +into the widget. + + + + +When the widget is unrealized: + +Destroy the Input Context. + + + + + +See the XLib reference manual for more detailed information on input methods, +and the #GtkEntry and #GtkText widgets for some example code. + + +Input Contexts + +Used for each widget that handles internationalized text input using the +global input method. + + + - +A set of bit-flags used to specify the input method styles which are supported +or which are currently in use. The flags can be divided into 2 groups, the +pre-edit flags and the status flags. - -@GDK_IM_PREEDIT_AREA: -@GDK_IM_PREEDIT_CALLBACKS: -@GDK_IM_PREEDIT_POSITION: -@GDK_IM_PREEDIT_NOTHING: -@GDK_IM_PREEDIT_NONE: -@GDK_IM_PREEDIT_MASK: -@GDK_IM_STATUS_AREA: -@GDK_IM_STATUS_CALLBACKS: -@GDK_IM_STATUS_NOTHING: -@GDK_IM_STATUS_NONE: -@GDK_IM_STATUS_MASK: - - - +The pre-edit flags specify how pre-editing data is displayed. +For example, this could display the text being typed in in the phonetic +alphabet before it is composed and inserted as an ideograph. - - - - +The status flags specify how status information is displayed. +The status information can be thought of as an extension of the +standard keyboard mode indicators, such as the Caps Lock indicator. - -@Returns: - - - + - +The %GDK_IM_PREEDIT_CALLBACKS and %GDK_IM_STATUS_CALLBACKS styles are not +currently supported in GTK+. + + +@GDK_IM_PREEDIT_AREA: The application provides the input method with an area +in which to perform off-the-spot pre-editing. +@GDK_IM_PREEDIT_CALLBACKS: The application registers a number of callback +functions which are used to display pre-editing data. +@GDK_IM_PREEDIT_POSITION: The application provides the input method with the +position of the insertion cursor, for over-the-spot +pre-editing. The input method creates its own window over the widget to +display the pre-editing data. +@GDK_IM_PREEDIT_NOTHING: The input method uses the root X window to perform +pre-editing, so the application does not need to do anything. +@GDK_IM_PREEDIT_NONE: No pre-editing is done by the input method, or no +pre-editing data needs to be displayed. +@GDK_IM_PREEDIT_MASK: A bit-mask containing all the pre-edit flags. +@GDK_IM_STATUS_AREA: The application provides the input method with an area +in which to display status information. +@GDK_IM_STATUS_CALLBACKS: The applications registers a number of callback +functions which are used to display status information. +@GDK_IM_STATUS_NOTHING: The input method uses the root X window to display +status information, so the application does not need to do anything. +@GDK_IM_STATUS_NONE: The input method does not display status information. +@GDK_IM_STATUS_MASK: A bit-mask containing all the status flags. -@ic: -@window: - - - + - +Checks if an input method is to be used for the current locale. +If GTK+ has been compiled without support for input methods, or the current +locale doesn't need an input method, then this will return FALSE. +@Returns: TRUE if an input method is available and should be used. - +Decides which input method style should be used, by comparing the styles given +in @supported_style with those of the available input method. -@supported_style: -@Returns: +@supported_style: styles which are supported by the widget. +@Returns: the best style in @supported_style that is also supported by the +available input method. - +Sets the best pre-edit and/or status style which should be used. +This will affect the style chosen in gdk_im_decide_style(). + + +The order of the pre-edit styles is (from worst to best): +%GDK_IM_PREEDIT_NONE, %GDK_IM_PREEDIT_NOTHING, %GDK_IM_PREEDIT_AREA, +%GDK_IM_PREEDIT_POSITION, %GDK_IM_PREEDIT_CALLBACKS. +The order of the status styles is: +%GDK_IM_STATUS_NONE, %GDK_IM_STATUS_NOTHING, %GDK_IM_STATUS_AREA, +%GDK_IM_STATUS_CALLBACKS. + + +So, for example, to set the best allowed pre-edit style to %GDK_IM_PREEDIT_AREA +you would do this: + + + + gdk_im_set_best_style (GDK_IM_PREEDIT_AREA); + + + +Or to set the best allowed pre-edit style to %GDK_IM_PREEDIT_POSITION and the +best allowed status style to %GDK_IM_STATUS_NOTHING you can do this: + + + + gdk_im_set_best_style (GDK_IM_PREEDIT_POSITION | GDK_IM_STATUS_NOTHING); + + -@best_allowed_style: -@Returns: +@best_allowed_style: a bit-mask with the best pre-edit style and/or the best +status style to use. If 0 is used, then the current bit-mask of all allowed +styles is returned. +@Returns: a bit-mask of all the styles allowed. - + - +Starts editing, using the given #GdkInputContext and #GdkWindow. +This should be called when the widget receives the input focus, typically in +the widget's focus_in_event method. -@src: -@Returns: +@ic: a #GdkInputContext. +@window: the #GdkWindow which will be receiving the key press events. - + - +Stops editing using the input method. +This should be called when the widget loses the input focus, typically in +the widget's focus_out_event method. -@dest: -@src: -@dest_max: -@Returns: diff --git a/docs/reference/gdk/tmpl/properties.sgml b/docs/reference/gdk/tmpl/properties.sgml index bce80d2e7e..d792214a1c 100644 --- a/docs/reference/gdk/tmpl/properties.sgml +++ b/docs/reference/gdk/tmpl/properties.sgml @@ -49,6 +49,13 @@ of strings on the X server. + + + + + + + Convert a text string from the encoding as it is stored in diff --git a/docs/reference/gdk/tmpl/regions.sgml b/docs/reference/gdk/tmpl/regions.sgml index dcb3b89682..32087e1d66 100644 --- a/docs/reference/gdk/tmpl/regions.sgml +++ b/docs/reference/gdk/tmpl/regions.sgml @@ -88,90 +88,97 @@ Creates a new empty #GdkRegion. @Returns: a new empty #GdkRegion. - + -Destroys a #GdkRegion. +Creates a new #GdkRegion using the polygon defined by a number of points. + -@region: a #GdkRegion. +@points: an array of #GdkPoint structs. +@npoints: the number of elements in the @points array. +@fill_rule: specifies which pixels are included in the region when the polygon +overlaps itself. +@Returns: a new #GdkRegion based on the given polygon. - + -Returns the smallest rectangle which includes the entire #GdkRegion. +The method for determining which pixels are included in a region, when +creating a #GdkRegion from a polygon. +The fill rule is only relevant for polygons which overlap themselves. -@region: a #GdkRegion. -@rectangle: returns the smallest rectangle which includes all of @region. +@GDK_EVEN_ODD_RULE: areas which are overlapped an odd number of times are +included in the region, while areas overlapped an even number of times are not. +@GDK_WINDING_RULE: overlapping areas are always included. - - + -Returns TRUE if the #GdkRegion is empty. +Destroys a #GdkRegion. @region: a #GdkRegion. -@Returns: TRUE if @region is empty. - + -Returns TRUE if the two regions are the same. +Returns the intersection of two regions. -@region1: a #GdkRegion. -@region2: a #GdkRegion. -@Returns: TRUE if @region1 and @region2 are equal. +@source1: a #GdkRegion. +@source2: a #GdkRegion. +@Returns: the intersection of @source1 and @source2. - + -Returns TRUE if a point is in a region. +Returns the union of two regions. +This is all pixels in either of @source1 or @source2. -@region: a #GdkRegion. -@x: the x coordinate of a point. -@y: the y coordinate of a point. -@Returns: TRUE if the point is in @region. +@source1: a #GdkRegion. +@source2: a #GdkRegion. +@Returns: the union of @source1 and @source2. - + -Tests whether a rectangle is within a region. +Subtracts one region from another. +The result is a region containing all the pixels which are in @source1, but +which are not in @source2. -@region: a #GdkRegion. -@rect: a #GdkRectangle. -@Returns: GDK_OVERLAP_RECTANGLE_IN, GDK_OVERLAP_RECTANGLE_OUT, or -GDK_OVERLAP_RECTANGLE_PART, depending on whether the rectangle is inside, -outside, or partly inside the #GdkRegion, respectively. +@source1: a #GdkRegion. +@source2: a #GdkRegion to subtract from @source1. +@Returns: @source1 - @source2. - + -Specifies the possible values returned by gdk_region_rect_in(). +Returns the difference between the union and the intersection of two regions. +This is a region containing the pixels that are in one of the source regions, +but which are not in both. -@GDK_OVERLAP_RECTANGLE_IN: if the rectangle is inside the #GdkRegion. -@GDK_OVERLAP_RECTANGLE_OUT: if the rectangle is outside the #GdkRegion. -@GDK_OVERLAP_RECTANGLE_PART: if the rectangle is partly inside the #GdkRegion. +@source1: a #GdkRegion. +@source2: a #GdkRegion. +@Returns: the difference between the union and the intersection of @source1 +and @source2. - - -Creates a new #GdkRegion using the polygon defined by a number of points. + + +Returns the union of a region and a rectangle. -@points: an array of #GdkPoint structs. -@npoints: the number of elements in the @points array. -@fill_rule: specifies which pixels are included in the region when the polygon -overlaps itself. -@Returns: a new #GdkRegion based on the given polygon. +@region: a #GdkRegion. +@rect: a #GdkRectangle. +@Returns: the union of @region and @rect. -Moves a region. +Moves a region the specified distance. @region: a #GdkRegion. @@ -181,67 +188,72 @@ Moves a region. -Resizes a region. +Resizes a region by the specified amount. +Positive values shrink the region. Negative values expand it. @region: a #GdkRegion. -@dx: -@dy: +@dx: the number of pixels to shrink the region horizontally. +@dy: the number of pixels to shrink the region vertically. - + -Returns the union of a region and a rectangle. +Returns TRUE if the #GdkRegion is empty. @region: a #GdkRegion. -@rect: a #GdkRectangle. -@Returns: the union of @region and @rect. +@Returns: TRUE if @region is empty. - + -Returns the intersection of two regions. +Returns TRUE if the two regions are the same. -@source1: a #GdkRegion. -@source2: a #GdkRegion. -@Returns: the intersection of @source1 and @source2. +@region1: a #GdkRegion. +@region2: a #GdkRegion. +@Returns: TRUE if @region1 and @region2 are equal. - + -Returns the union of two regions. -This is all pixels in either of @source1 or @source2. +Returns TRUE if a point is in a region. -@source1: a #GdkRegion. -@source2: a #GdkRegion. -@Returns: the union of @source1 and @source2. +@region: a #GdkRegion. +@x: the x coordinate of a point. +@y: the y coordinate of a point. +@Returns: TRUE if the point is in @region. - + -Subtracts one region from another. -The result is a region containing all the pixels which are in @source1, but -which are not in @source2. +Tests whether a rectangle is within a region. -@source1: a #GdkRegion. -@source2: a #GdkRegion to subtract from @source1. -@Returns: @source1 - @source2. +@region: a #GdkRegion. +@rect: a #GdkRectangle. +@Returns: GDK_OVERLAP_RECTANGLE_IN, GDK_OVERLAP_RECTANGLE_OUT, or +GDK_OVERLAP_RECTANGLE_PART, depending on whether the rectangle is inside, +outside, or partly inside the #GdkRegion, respectively. - + -Returns the difference between the union and the intersection of two regions. -This is a region containing the pixels that are in one of the source regions, -but which are not in both. +Specifies the possible values returned by gdk_region_rect_in(). -@source1: a #GdkRegion. -@source2: a #GdkRegion. -@Returns: the difference between the union and the intersection of @source1 -and @source2. +@GDK_OVERLAP_RECTANGLE_IN: if the rectangle is inside the #GdkRegion. +@GDK_OVERLAP_RECTANGLE_OUT: if the rectangle is outside the #GdkRegion. +@GDK_OVERLAP_RECTANGLE_PART: if the rectangle is partly inside the #GdkRegion. + + + +Returns the smallest rectangle which includes the entire #GdkRegion. + + +@region: a #GdkRegion. +@rectangle: returns the smallest rectangle which includes all of @region. diff --git a/docs/reference/gdk/tmpl/rgb.sgml b/docs/reference/gdk/tmpl/rgb.sgml index 928753dc61..9fb49ec5bb 100644 --- a/docs/reference/gdk/tmpl/rgb.sgml +++ b/docs/reference/gdk/tmpl/rgb.sgml @@ -125,7 +125,6 @@ on_darea_expose (GtkWidget *widget, - @@ -140,49 +139,6 @@ colors. - - -A private data structure which maps color indices to actual RGB -colors. This is used only for gdk_draw_indexed_image(). - - - - - - -Selects whether or not GdkRgb applies dithering -to the image on display. There are three values: - - - - - - -%GDK_RGB_DITHER_NONE: Never use dithering. - - - - - -%GDK_RGB_DITHER_NORMAL: Use dithering in 8 bits per pixel (and below) -only. - - - - - -%GDK_RGB_DITHER_MAX: Use dithering in 16 bits per pixel and below. - - - - - - -Since GdkRgb currently only handles images with 8 bits per component, -dithering on 24 bit per pixel displays is a moot point. - - - Initializes GdkRgb statically. It may be called more than once with no @@ -199,46 +155,6 @@ the chosen visual and colormap, respectively. - - -Creates a new #GdkRgbCmap structure. The cmap maps color indexes to -RGB colors. If @n_colors is less than 256, then images containing -color values greater than or equal to @n_colors will produce undefined -results, including possibly segfaults. - - -@colors: The colors, represented as 0xRRGGBB integer values. -@n_colors: The number of colors in the cmap. -@Returns: The newly created #GdkRgbCmap - - - - -Frees the memory associated with a #GdkRgbCmap created by gdk_rgb_cmap_new(). - - -@cmap: The #GdkRgbCmap to free. - - - - -Sets the foreground color in @gc to the specified color (or the -closest approximation, in the case of limited visuals). - - -@gc: The @GdkGC to modify. -@rgb: The color, represented as a 0xRRGGBB integer value. - - - - -Sets the background color in @gc to the specified color (or the -closest approximation, in the case of limited visuals). - - -@gc: The @GdkGC to modify. -@rgb: The color, represented as a 0xRRGGBB integer value. - @@ -270,12 +186,45 @@ contents are ignored). @y: The y coordinate of the top-left corner in the drawable. @width: The width of the rectangle to be drawn. @height: The height of the rectangle to be drawn. -@dith: A #GdkRgbDither value, selecting the desired dither mode. +@dith: A #GdkRgbDither value, selecting the desired dither mode. @rgb_buf: The pixel data, represented as packed 24-bit data. @rowstride: The number of bytes from the start of one row in @rgb_buf to the start of the next. + + +Draws an RGB image in the drawable, with an adjustment for dither alignment. + + + +This function is useful when drawing dithered images into a window +that may be scrolled. Pixel (x, y) will be drawn dithered as if its +actual location is (x + @xdith, y + @ydith). Thus, if you draw an +image into a window using zero dither alignment, then scroll up one +pixel, subsequent draws to the window should have @ydith = 1. + + + +Setting the dither alignment correctly allows updating of small parts +of the screen while avoiding visible "seams" between the different +dither textures. + + +@drawable: The #GdkDrawable to draw in (usually a #GdkWindow). +@gc: The graphics context. +@x: The x coordinate of the top-left corner in the drawable. +@y: The y coordinate of the top-left corner in the drawable. +@width: The width of the rectangle to be drawn. +@height: The height of the rectangle to be drawn. +@dith: A #GdkRgbDither value, selecting the desired dither mode. +@rgb_buf: The pixel data, represented as packed 24-bit data. +@rowstride: The number of bytes from the start of one row in @rgb_buf to the +start of the next. +@xdith: An x offset for dither alignment. +@ydith: A y offset for dither alignment. + + Draws an indexed image in the drawable, using a #GdkRgbCmap to assign @@ -288,7 +237,7 @@ actual colors to the color indices. @y: The y coordinate of the top-left corner in the drawable. @width: The width of the rectangle to be drawn. @height: The height of the rectangle to be drawn. -@dith: A #GdkRgbDither value, selecting the desired dither mode. +@dith: A #GdkRgbDither value, selecting the desired dither mode. @buf: The pixel data, represented as 8-bit color indices. @rowstride: The number of bytes from the start of one row in @buf to the start of the next. @@ -301,14 +250,13 @@ Draws a grayscale image in the drawable. - @drawable: The #GdkDrawable to draw in (usually a #GdkWindow). @gc: The graphics context. @x: The x coordinate of the top-left corner in the drawable. @y: The y coordinate of the top-left corner in the drawable. @width: The width of the rectangle to be drawn. @height: The height of the rectangle to be drawn. -@dith: A #GdkRgbDither value, selecting the desired dither mode. +@dith: A #GdkRgbDither value, selecting the desired dither mode. @buf: The pixel data, represented as 8-bit gray values. @rowstride: The number of bytes from the start of one row in @buf to the start of the next. @@ -334,73 +282,110 @@ memory bandwidth. @y: The y coordinate of the top-left corner in the drawable. @width: The width of the rectangle to be drawn. @height: The height of the rectangle to be drawn. -@dith: A #GdkRgbDither value, selecting the desired dither mode. +@dith: A #GdkRgbDither value, selecting the desired dither mode. @buf: The pixel data, represented as padded 32-bit data. @rowstride: The number of bytes from the start of one row in @buf to the start of the next. - + -Draws an RGB image in the drawable, with an adjustment for dither alignment. + +Selects whether or not GdkRgb applies dithering +to the image on display. There are three values: + + + -This function is useful when drawing dithered images into a window -that may be scrolled. Pixel (x, y) will be drawn dithered as if its -actual location is (x + @xdith, y + @ydith). Thus, if you draw an -image into a window using zero dither alignment, then scroll up one -pixel, subsequent draws to the window should have @ydith = 1. +%GDK_RGB_DITHER_NONE: Never use dithering. + + -Setting the dither alignment correctly allows updating of small parts -of the screen while avoiding visible "seams" between the different -dither textures. +%GDK_RGB_DITHER_NORMAL: Use dithering in 8 bits per pixel (and below) +only. + -@drawable: The #GdkDrawable to draw in (usually a #GdkWindow). -@gc: The graphics context. -@x: The x coordinate of the top-left corner in the drawable. -@y: The y coordinate of the top-left corner in the drawable. -@width: The width of the rectangle to be drawn. -@height: The height of the rectangle to be drawn. -@dith: A #GdkRgbDither value, selecting the desired dither mode. -@rgb_buf: The pixel data, represented as packed 24-bit data. -@rowstride: The number of bytes from the start of one row in @rgb_buf to the -start of the next. -@xdith: An x offset for dither alignment. -@ydith: A y offset for dither alignment. + + +%GDK_RGB_DITHER_MAX: Use dithering in 16 bits per pixel and below. + + + - -Finds the X pixel closest in color to the @rgb color specified. This -value may be used to set the pixel field of -a #GdkColor struct. +Since GdkRgb currently only handles images with 8 bits per component, +dithering on 24 bit per pixel displays is a moot point. +@GDK_RGB_DITHER_NONE: +@GDK_RGB_DITHER_NORMAL: +@GDK_RGB_DITHER_MAX: + + + +Creates a new #GdkRgbCmap structure. The cmap maps color indexes to +RGB colors. If @n_colors is less than 256, then images containing +color values greater than or equal to @n_colors will produce undefined +results, including possibly segfaults. + + +@colors: The colors, represented as 0xRRGGBB integer values. +@n_colors: The number of colors in the cmap. +@Returns: The newly created #GdkRgbCmap + + + + +Frees the memory associated with a #GdkRgbCmap created by gdk_rgb_cmap_new(). + + +@cmap: The #GdkRgbCmap to free. + + + + +A private data structure which maps color indices to actual RGB +colors. This is used only for gdk_draw_indexed_image(). + + +@colors: +@lut: + + + +Sets the foreground color in @gc to the specified color (or the +closest approximation, in the case of limited visuals). + + +@gc: The #GdkGC to modify. @rgb: The color, represented as a 0xRRGGBB integer value. -@Returns: The X pixel value. - + -Sets the "verbose" flag. This is generally only useful for debugging. +Sets the background color in @gc to the specified color (or the +closest approximation, in the case of limited visuals). -@verbose: TRUE if verbose messages are desired. +@gc: The #GdkGC to modify. +@rgb: The color, represented as a 0xRRGGBB integer value. - + -Determine whether the visual is ditherable. This function may be -useful for presenting a user interface choice to the user about which -dither mode is desired; if the display is not ditherable, it may make -sense to gray out or hide the corresponding UI widget. +Finds the X pixel closest in color to the @rgb color specified. This +value may be used to set the pixel field of +a #GdkColor struct. -@Returns: TRUE if the visual is ditherable. +@rgb: The color, represented as a 0xRRGGBB integer value. +@Returns: The X pixel value. @@ -436,7 +421,7 @@ Gets the visual chosen by GdkRgb. This visual and the corresponding colormap should be used when creating windows that will be drawn in by GdkRgb. -@Returns: The @GdkVisual chosen by GdkRgb. +@Returns: The #GdkVisual chosen by GdkRgb. @@ -445,6 +430,25 @@ Gets the colormap set by GdkRgb. This colormap and the corresponding visual should be used when creating windows that will be drawn in by GdkRgb. -@Returns: The @GdkColormap set by GdkRgb. +@Returns: The #GdkColormap set by GdkRgb. + + + + +Determine whether the visual is ditherable. This function may be +useful for presenting a user interface choice to the user about which +dither mode is desired; if the display is not ditherable, it may make +sense to gray out or hide the corresponding UI widget. + + +@Returns: TRUE if the visual is ditherable. + + + + +Sets the "verbose" flag. This is generally only useful for debugging. + + +@verbose: TRUE if verbose messages are desired. diff --git a/docs/reference/gdk/tmpl/selections.sgml b/docs/reference/gdk/tmpl/selections.sgml index be5ff5dc37..fbcde204a6 100644 --- a/docs/reference/gdk/tmpl/selections.sgml +++ b/docs/reference/gdk/tmpl/selections.sgml @@ -25,8 +25,9 @@ can be retrieved by requesting the special target TARGETS. When a selection is retrieved, the data is accompanied by a type (an atom), and a format (an integer, representing -the number of bits per item). See for more information. +the number of bits per item). +See Properties and Atoms +for more information. The functions in this section only contain the lowlevel @@ -96,7 +97,7 @@ compatibility with older programs. @GDK_TARGET_PIXMAP: A pixmap ID. @GDK_TARGET_STRING: A string encoded in ISO Latin-1. (With the additional of TAB - and NEWLINE.) + and NEWLINE.) @@ -148,6 +149,7 @@ form. request if it did not own the selection at the time indicated by the timestamp. + Retrieve selection data that was stored by the selection -- 2.30.2